Skip to main content
Give your chat experience UI superpowers: the agent replies with structured actions your frontend can run (e.g., open a product, fire confetti, toggle a theme).

​
What you’ll build

  • A CrewAI agent that returns JSON actions instead of calling backend APIs.
  • A tool definition that keeps action payloads predictable.
  • A /kickoff stream that includes tool_* events so the client can map actions.
  • A CometChat AI Agent entry that routes traffic to this CrewAI service.

​
Prerequisites

  • CrewAI project + FastAPI stream from crew-ai.mdx
  • Frontend capable of handling action payloads (UI Kit export or custom UI)
  • Optional: canvas-confetti or your own action handlers

​
Steps

1

Define allowed actions

Decide on a small set of actions your UI will accept (e.g., open_product, show_confetti, toggle_theme).
2

Create a CrewAI tool

Return structured JSON with action name and parameters. Keep the schema narrow to avoid unsafe payloads.
3

Instruct the agent

In the backstory, explain when to trigger each action and to keep text responses short when actions are returned.
4

Handle on the client

In your widget or UI Kit export, map tool_call_* + tool_result events to actual UI functions (e.g., fire confetti, navigate).

​
Sample action tool

src/crew_demo/tools/confetti_action.py 
import json
from crewai.tools import tool


@tool("trigger_confetti")
def trigger_confetti(celebration: str = "default") -> str:
    """Return a confetti action payload for the frontend."""
    return json.dumps({
        "action": "show_confetti",
        "parameters": {
            "preset": celebration,
            "particleCount": 150,
            "spread": 70
        }
    })
Register in crew.py and add to the agent’s tool list alongside any other actions.

​
Agent configuration

src/crew_demo/config/agents.yaml 
ui_assistant:
  role: Frontend Action Agent
  goal: Trigger approved UI actions and keep responses concise
  backstory: >
    When a user asks to celebrate, call trigger_confetti and include a short celebratory message.
    When a user asks to open a product, return an action with name=open_product and include productId.
    Never invent action names outside the approved list. Keep explanations brief.
src/crew_demo/config/tasks.yaml 
ui_task:
  description: >
    Decide whether to run a UI action for: {user_message}
  expected_output: >
    Either a short text response or a tool-triggered action.
  agent: ui_assistant

​
Client-side handling

  • Listen for tool_call_start/tool_call_args to show “running action…” states.
  • Parse tool_result JSON and map the action name to a handler.
  • Keep handlers idempotent and validate parameters on the client before executing.

​
Connect to CometChat

Use the same /kickoff endpoint as your CrewAI project. In Dashboard → AI Agents:
  • Provider: CrewAI
  • Agent ID: ui_assistant
  • Deployment URL: your /kickoff
  • (Optional) Suggested prompts: “Launch confetti”, “Open the product page for sku-123”